Skip to main content

Understanding consensus and splits

Unicrow keeps track of the current and final states of the escrow by consensus and splits. Let’s dive into how they work

Consensus​

Buyer’s and seller’s consensus keep track of the current (or final) state of each escrow via their respective integer values.

In simplest terms, when consensus value is positive for a party, that party “agrees” for the escrow to be claimed at any time in the current state. When it is negative, that party might not agree.

In the contract, they are defined in consensus field in the Escrow object

In the SDK, there are two separate parameters consensusBuyer and consensusSeller in IEscrowData interface

Some buyer or seller actions on the escrow change the values of the consensus:

  • Initial payment sets buyer’s consensus to 0, seller’s to 1 - in other words, seller agrees to claim the payment anytime (of course :-), buyer is still undecided
  • Release, Refund, or Settlement set both values to a positive number and increase buyer’s consensus by 1.
  • Challenge sets consensus of the challenging party to a positive number and increases it by 1, and sets the consensus of the challenged party to a negative number

The escrow can go through various stages in its lifecycle which can be mostly interpreted based on the consensus values. The following describes all of these states, each starting with [buyerConsensus, sellerConsensus] array

  • [ 0, 1]: Paid - the escrow was paid, no other action was taken on it. If the payment is claimed after challenge period ends, consensus remains like this
  • [ 1, 1]: Released by buyer, Refunded by the seller, or settled without a challenge (to find out which, look at split values, see below)
  • [ 1,-1]: 1x Challenged by buyer - If the payment is claimed after CP ends, consensus remains like this
  • [-1, 2]: 1x Challenged by buyer and 1x by Seller
  • [ 2,-2]: 2x Challenged by buyer, 1x by seller
  • [ 3, 2]: Released, Refunded, or Settled after a challenge. Deduct 1 from each consensus number to calculate number of challenges

Note: Arbitration doesn’t change the consensus values.

Splits​

The splits define how the balance is currently set to be split between all the parties except the arbitrator, i.e.:

  • Buyer (0 by default, 100 in case of refund, anything between in case of settlement)
  • Seller (100 by default, 0 in case of refund, anything between in case of settlement)
  • Marketplace (% fee set in the escrow parameters)
  • Protocol (% fee set by governance)

In contracts, the splits are set in the Escrow object

In the SDK, the splits are returned in the IEscrowData object

The marketplace and protocol fees are written to the escrow parameters at the time of the payment and never change (even though the fees are not paid in case of refund).

However, buyer and seller splits can change based on user’s actions on the escrow:

  • Challenge sets splits to 100, 0 in favor of the party who challenged
  • Settlement sets the splits to anything between based on the agreement
  • Arbitration can set any values as long as they sum up to 100

The buyer and seller splits summed up always equal 100 even when the other fees are set. In other words, during the full lifecycle of the escrow, splits + fees are always greater than 100%. That is to avoid having to calculate all the splits at the time of the payment and other actions.

When the payment is being claimed in any state, the contract recalculates all the final values based on the buyer/seller split and on the fees (including arbitrator fee which is set elsewhere).

More on the fee calculation in a separate section.